This page last changed on Jul 05, 2006 by aperepel.

Mule's transaction framework is agnostic to the underlying transaction manager. The transaction could be a JDBC transaction, XA transaction or a JMS transaction or message acknowledgment. Whatever type the transaction is it can be handled the same way. Mule transactions are configured on inbound endpoints, where an endpoint can be configured to start a new transaction or join an existing one. The outbound endpoints will automatically enlist in the current transaction, provided that the managed resource is compatible with the transaction. Transactions are configured on a endpoint using a <transaction> which maps to org.mule.umo.transaction.UMOTransactionConfig class. This defines what action an endpoint should take when it receives an event and the transaction factory to use to create transactions.

Single resource transactions

Single resource transactions are transactions that are provided by the underlying resource:
a jdbc transaction or a jms transaction.
These kind of transactions can only be used to receive and/or send messages using a single resource.

Example inbound endpoint configuration might look like -

<endpoint name="myInboundEndpoint" type="receiver" address="jms://test.In">
    <transaction action="ALWAYS_BEGIN" factory="org.mule.providers.jms.JmsTransactionFactory" />
</endpoint>

The configuration defines a JMS message endpoint that sends on a 'test.out' queue. The factory attribute is a fully qualified path to a TransactionFactory which Mule will use when creating transactions for this endpoint. The action attribute tells Mule what to do for each event, in this case a new transaction will be created for every event received. Possible values for action on the <tx-inbound> element are -

  • NONE - Never participate in a transaction.
  • ALWAYS_BEGIN - Always start a new transaction when receiving an event. An exception will be thrown if a transaction already exists
  • BEGIN_OR_JOIN - If a transaction is already in progress when an event is received, join the transaction, otherwise start a new transaction
  • ALWAYS_JOIN - Always expects a transaction to be in progress when an event is received, if there is no transaction an exception is thrown.
  • JOIN_IF_POSSIBLE - Will join the current transaction if one is available otherwise no transaction is created.

The outbound endpoint has no particular configuration:

<endpoint name="myOutboundEndpoint" type="sender" address="jms://test.Out" />

The outbound endpoint will use the resource enlisted in the current transaction, if one is running.
In this case, it will use the same jms session that has been used to receive the event. So when the inbound
endpoint will have routed the message to the outbound endpoint, the transaction will be commited or rollbacked.

You can send multiple message using the recipient list router and all messages
will be sent in the same transaction.

XA transactions

XA transactions can be used if you want to enlist multiple managed resources within the same transaction.
The inbound endpoints are configured in the same manner as for single resource transactions,
but the connectors need to be configured to use xa-enabled resources.

If you run mule outside an application server, you can use Jotm transaction manager to configure an embedded transaction manager or read the next section.

Currently, only three providers can be configured to be used in xa transactions:

XA Configuration Example

The following uses a single transaction to read from a Jms Queue and write to a database.

<mule-descriptor name="JmsToJdbc" implementation="org.foo.MyComponent">
    <inbound-router>
        <endpoint address="jms://my.queue?reuseSession=false">
	    <transaction action="ALWAYS_BEGIN" factory="org.mule.transaction.XaTransactionFactory" timeout="60000"/>
	</endpoint>
    </inbound-router>
    <outbound-router>
        <router className="org.mule.routing.outbound.OutboundPassThroughRouter">
            <endpoint address="jdbc://writeTest?type=2" />
        </router>
    </outbound-router>
</mule-descriptor>

Because the inbound Jms Endpoint has an XATransactionFactory configured on it any outbound endpoints for the component will also become part of the XA transaction providing that the transport type supports XA transactions (XA enabled transports are listed above). For this configuration to work you will need to configure a Jms connector that uses a Jms XA Connection Factory and a Jdbc connector that is configured to use an XA DataSource.

Transaction Manager Lookup

Mule uses javax.transaction.TransactionManager for managing transaction spanning multiple resources (XA). If you need the SUSPEND semantics for your transactions (i.e. this is what EJB's RequiresNew Tx attribute value does), then you have to use the transaction manager. Contrast this to a more typical javax.transaction.UserTransaction, which is just a thin handle to a transaction manager with limited (though in most cases sufficient) functionality. Particularly, it will not let you suspend the current transaction, otherwise it's merely the same.

Depending on your server, you can run Mule either standalone or embedded in the application server. This is not only your choice, but a requirement for some products, as one server will expose the transaction manager in JNDI, the other will not, and yet another will grant you access only via proprietary APIs. This is unfortunate, but still in line with Java EE 1.4 specification, which does not consider the transaction manager a public API. Thus, you are left to the mercy of your application server vendor.

The following table summarizes some common Java EE servers:

Application Server Remote Embedded Common Location Lookup class
JBoss java:/TransactionManager org.mule.transaction.lookup.JBossTransactionManagerLookupFactory
Weblogic javax.transaction.TransactionManager org.mule.transaction.lookup.WeblogicTransactionManagerLookupFactory
WebSphere Proprietary API call org.mule.transaction.lookup.WebsphereTransactionManagerLookupFactory
Resin java:comp/TransactionManager org.mule.transaction.lookup.Resin3TransactionManagerLookupFactory
JRun java:/TransactionManager org.mule.transaction.lookup.JRunTransactionManagerLookupFactory
Other specified via a jndiName property org.mule.transaction.lookup.GenericTransactionManagerLookupFactory

E.g. to use Weblogic's transaction manager:

<transaction-manager factory="org.mule.transaction.lookup.WeblogicTransactionManagerLookupFactory" />

Transaction Coordination

Transaction demarcation is controlled by endpoints. The actual management of transactions is handled by the Mule TransactionCoordinator. Its important to note that any transacted event flows will be synchronous. The TransactionCoordinator is a singleton manager that looks after all the transactions for a Mule instance and provides methods for binding and unbinding transaction and retrieving the current transaction state.

Document generated by Confluence on Nov 27, 2006 10:27